home *** CD-ROM | disk | FTP | other *** search
/ Australian Personal Computer 2002 November / CD 1 / APC0211D1.ISO / workshop / prog / files / ActivePerl-5.6.1.633-MSWin32.msi / _9b071c0441420364ce0ee7cf48dbcc5c < prev    next >
Encoding:
Text File  |  2002-05-30  |  7.3 KB  |  240 lines
  1. # $Id: configspec.pod 1.2 Wed, 12 Nov 1997 00:30:45 +0100 ach $
  2.  
  3. =head1 NAME
  4.  
  5. Tk::ConfigSpecs - Defining behaviour of 'configure' for composite widgets.
  6.  
  7. =for category Derived Widgets
  8.  
  9. =head1 SYNOPSIS
  10.  
  11.     sub Populate
  12.     {
  13.      my ($composite,$args) = @_;
  14.      ...
  15.      $composite->ConfigSpecs('-attribute' => [ where,dbName,dbClass,default ]);
  16.      $composite->ConfigSpecs('-alias' => '-otherattribute');
  17.      $composite->ConfigSpecs('DEFAULT' => [ where ]);
  18.      ...
  19.     }
  20.  
  21.     $composite->configure(-attribute => value);
  22.  
  23. =head1 DESCRIPTION
  24.  
  25. The aim is to make the composite widget configure method look as much like
  26. a regular Tk widget's configure as possible.
  27. (See L<Tk::options> for a description of this behaviour.)
  28. To enable this the attributes that the composite as a whole accepts
  29. needs to be defined.
  30.  
  31. =head2 Defining the ConfigSpecs for a class.
  32.  
  33. Typically a widget will have one or more calls like the following
  34.  
  35.     $composite->ConfigSpecs(-attribute => [where,dbName,dbClass,default]);
  36.  
  37. in its B<Populate> method. When B<ConfigSpecs> is called this way
  38. (with arguments) the arguments are used to construct or augment/replace
  39. a hash table for the widget. (More than one I<-option>=E<gt>I<value>
  40. pair can be specified to a single call.)
  41.  
  42. B<dbName>, B<dbClass> and default are only used by B<ConfigDefault> described
  43. below, or to respond to 'inquiry' configure commands.
  44.  
  45. It may be either one of the values below, or a list of such values
  46. enclosed in B<[]>.
  47.  
  48. The currently permitted values of B<where> are:
  49.  
  50. =over 4
  51.  
  52. =item B<'ADVERTISED'>
  53.  
  54. apply B<configure> to I<advertised> subwidgets.
  55.  
  56. =item B<'DESCENDANTS'>
  57.  
  58. apply B<configure> recursively to all descendants.
  59.  
  60. =item B<'CALLBACK'>
  61.  
  62. Setting the attribute does C<Tk::Callback-E<gt>new($value)> before storing
  63. in C<$composite-E<gt>{Configure}{-attribute}>. This is appropriate for
  64. C<-command =E<gt> ...> attributes that are handled by the composite and not
  65. forwarded to a subwidget. (E.g. B<Tk::Tiler> has C<-yscrollcommand> to
  66. allow it to have scrollbar attached.)
  67.  
  68. This may be the first of several 'validating' keywords (e.g. font, cursor,
  69. anchor etc.) that core Tk makes special for C code.
  70.  
  71. =item B<'CHILDREN'>
  72.  
  73. apply B<configure> to all children.  (Children are the immediate
  74. descendants of a widget.)
  75.  
  76. =item B<'METHOD'>
  77.  
  78. Call C<$cw-E<gt>attribute(value)>
  79.  
  80. This is the most general case. Simply have a method of the composite
  81. class with the same name as the attribute.  The method may do any
  82. validation and have whatever side-effects you like.  (It is probably
  83. worth 'queueing' using B<afterIdle> for more complex side-effects.)
  84.  
  85. =item B<'PASSIVE'>
  86.  
  87. Simply store value in C<$composite-E<gt>{Configure}{-attribute}>.
  88.  
  89. This form is also a useful placeholder for attributes which you
  90. currently only handle at create time.
  91.  
  92. =item B<'SELF'>
  93.  
  94. Apply B<configure> to the core widget (e.g. B<Frame>) that is the basis of
  95. the composite. (This is the default behaviour for most attributes which
  96. makes a simple Frame behave the way you would expect.) Note that once
  97. you have specified B<ConfigSpecs> for an attribute you must explicitly
  98. include C<'SELF'> in the list if you want the attribute to apply to the
  99. composite itself (this avoids nasty infinite recursion problems).
  100.  
  101. =item B<$reference> (blessed)
  102.  
  103. Call B<$reference>->configure(-attribute => value)
  104.  
  105. A common case is where B<$reference> is a subwidget.
  106.  
  107. $reference may also be result of
  108.  
  109.      Tk::Config->new(setmethod,getmethod,args,...);
  110.  
  111. B<Tk::Config> class is used to implement all the above keyword types.  The
  112. class has C<configure> and C<cget> methods so allows higher level code to
  113. I<always> just call one of those methods on an I<object> of some kind.
  114.  
  115. =item B<hash reference>
  116.  
  117. Defining:
  118.  
  119.     $cw->ConfigSpecs(
  120.         ...
  121.         -option => [ { -optionX=>$w1, -optionY=>[$w2, $w3] },
  122.                 dbname dbclass default ],
  123.         ...
  124.         );
  125.  
  126. So C<$cw-E<gt>configure(-option =E<gt> value)> actually does
  127.  
  128.     $w1->configure(-optionX => value);
  129.     $w2->configure(-optionY => value);
  130.     $w3->configure(-optionY => value);
  131.  
  132. =item B<'otherstring'>
  133.  
  134. Call
  135.  
  136.     $composite->Subwidget('otherstring')->configure( -attribute => value );
  137.  
  138. While this is here for backward compatibility with Tk-b5, it is probably
  139. better just to use the subwidget reference directly.  The only
  140. case for retaining this form is to allow an additional layer of
  141. abstraction - perhaps having a 'current' subwidget - this is unproven.
  142.  
  143. =item B<Aliases>
  144.  
  145. C<ConfigSpecs( -alias =E<gt> '-otherattribute' )> is used to make C<-alias>
  146. equivalent to C<-otherattribute>. For example the aliases
  147.  
  148.     -fg => '-foreground',
  149.     -bg => '-background'
  150.  
  151. are provided automatically (if not already specified).
  152.  
  153. =back
  154.  
  155. =head2 Default Values
  156.  
  157. When the B<Populate> method returns B<ConfigDefault> is called.  This calls
  158.  
  159.     $composite->ConfigSpecs;
  160.  
  161. (with no arguments) to return a reference to a hash. Entries in the hash
  162. take the form:
  163.  
  164.     '-attribute' => [ where, dbName, dbClass, default ]
  165.  
  166. B<ConfigDefault> ignores 'where' completely (and also the DEFAULT entry) and
  167. checks the 'options' database on the widget's behalf, and if an entry is
  168. present matching dbName/dbClass
  169.  
  170.     -attribute => value
  171.  
  172. is added to the list of options that B<new> will eventually apply to the
  173. widget. Likewise if there is not a match and default is defined this
  174. default value will be added.
  175.  
  176. Alias entries in the hash are used to convert user-specified values for the
  177. alias into values for the real attribute.
  178.  
  179. =head2 New()-time Configure
  180.  
  181. Once control returns to B<new>, the list of user-supplied options
  182. augmented by those from B<ConfigDefault> are applied to the widget using the
  183. B<configure> method below.
  184.  
  185. Widgets are most flexible and most Tk-like if they handle the majority of
  186. their attributes this way.
  187.  
  188. =head2 Configuring composites
  189.  
  190. Once the above have occurred calls of the form:
  191.  
  192.     $composite->configure( -attribute => value );
  193.  
  194. should behave like any other widget as far as end-user code is concerned.
  195. B<configure> will be handled by B<Tk::Derived::configure> as follows:
  196.  
  197.     $composite->ConfigSpecs;
  198.  
  199. is called (with no arguments) to return a reference to a hash B<-attribute> is
  200. looked up in this hash, if B<-attribute> is not present in the hash then
  201. B<'DEFAULT'> is looked for instead.  (Aliases are tried as well and cause
  202. redirection to the aliased attribute).  The result should be a reference to a
  203. list like:
  204.  
  205.   [ where, dbName, dbClass, default ]
  206.  
  207. at this stage only I<where> is of interest, it maps to a list of object
  208. references (maybe only one) foreach one
  209.  
  210.    $object->configure( -attribute => value );
  211.  
  212. is B<eval>ed.
  213.  
  214. =head2 Inquiring attributes of composites
  215.  
  216.    $composite->cget( '-attribute' );
  217.  
  218. This is handled by  B<Tk::Derived::cget> in a similar manner to configure. At
  219. present if I<where> is a list of more than one object it is ignored completely
  220. and the "cached" value in
  221.  
  222.    $composite->{Configure}{-attribute}.
  223.  
  224. is returned.
  225.  
  226. =head1 CAVEATS
  227.  
  228. It is the author's intention to port as many of the "Tix" composite widgets
  229. as make sense. The mechanism described above may have to evolve in order to
  230. make this possible, although now aliases are handled I think the above is
  231. sufficient.
  232.  
  233. =head1 SEE ALSO
  234.  
  235. L<Tk::composite|Tk::composite>,
  236. L<Tk::options|Tk::options>
  237.  
  238. =cut
  239.  
  240.